home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / catD / xtalk_pio.z / xtalk_pio
Encoding:
Text File  |  2002-10-03  |  11.1 KB  |  331 lines
  1.  
  2.  
  3.  
  4. xxxxttttaaaallllkkkk____ppppiiiioooo((((DDDD3333))))                                                    xxxxttttaaaallllkkkk____ppppiiiioooo((((DDDD3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      _xxxx_tttt_aaaa_llll_kkkk______pppp_iiii_oooo______aaaa_dddd_dddd_rrrr - construct PIO address
  10.      _xxxx_tttt_aaaa_llll_kkkk______pppp_iiii_oooo_tttt_rrrr_aaaa_nnnn_ssss______aaaa_dddd_dddd_rrrr - construct PIO address
  11.      _xxxx_tttt_aaaa_llll_kkkk______pppp_iiii_oooo_mmmm_aaaa_pppp______aaaa_llll_llll_oooo_cccc - allocate an XIO PIO channel
  12.      _xxxx_tttt_aaaa_llll_kkkk______pppp_iiii_oooo_mmmm_aaaa_pppp______aaaa_dddd_dddd_rrrr - set PIO channel target
  13.      _xxxx_tttt_aaaa_llll_kkkk______pppp_iiii_oooo_mmmm_aaaa_pppp______dddd_oooo_nnnn_eeee - mark PIO channel unused
  14.      _xxxx_tttt_aaaa_llll_kkkk______pppp_iiii_oooo_mmmm_aaaa_pppp______ffff_rrrr_eeee_eeee - release XIO PIO channel resources
  15.  
  16. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  17.      #include <sys/XIO/xtalk.h>
  18.  
  19.      caddr_t
  20.      xtalk_pio_addr(vertex_hdl_t _v_h_d_l,
  21.           device_desc_t _d_e_s_c,
  22.           iopaddr_t _a_d_d_r,
  23.           size_t _s_i_z_e,
  24.           xtalk_piomap_t *_m_a_p_p,
  25.           unsigned _f_l_a_g_s)
  26.  
  27.      caddr_t
  28.      xtalk_piotrans_addr(vertex_hdl_t _v_h_d_l,
  29.           device_desc_t _d_e_s_c,
  30.           iopaddr_t _a_d_d_r,
  31.           size_t _s_i_z_e,
  32.           unsigned _f_l_a_g_s)
  33.  
  34.      xtalk_piomap_t
  35.      xtalk_piomap_alloc(vertex_hdl_t _v_h_d_l,
  36.           device_desc_t _d_e_s_c,
  37.           iopaddr_t _a_d_d_r,
  38.           size_t _s_i_z_e,
  39.           size_t _m_a_x,
  40.           unsigned _f_l_a_g_s)
  41.  
  42.      caddr_t
  43.      xtalk_piomap_addr(xtalk_piomap_t _m_a_p,
  44.           iopaddr_t addr,
  45.           size_t size);
  46.  
  47.      void
  48.      xtalk_piomap_done(xtalk_piomap_t _x_t_a_l_k__p_i_o_m_a_p)
  49.  
  50.      void
  51.      xtalk_piomap_free(xtalk_piomap_t _x_t_a_l_k__p_i_o_m_a_p)
  52.  
  53.  
  54.    AAAArrrrgggguuuummmmeeeennnnttttssss
  55.      _v_h_d_l    is the appropriate XIO connection point.
  56.  
  57.      _d_e_s_c    is a device descriptor, usually zero.
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. xxxxttttaaaallllkkkk____ppppiiiioooo((((DDDD3333))))                                                    xxxxttttaaaallllkkkk____ppppiiiioooo((((DDDD3333))))
  71.  
  72.  
  73.  
  74.      _a_d_d_r    is the XIO address on the target device.
  75.  
  76.      _s_i_z_e    is the size of the mapped region.
  77.  
  78.      _a_l_i_g_n   is a desired alignment.
  79.  
  80.      _m_a_x     is the maximum size mapped at any one time.
  81.  
  82.      _f_l_a_g_s   is reserved and should be zero.
  83.  
  84.      _m_a_p     is the result of a previous xtalk_piomap_alloc call.
  85.  
  86.      _m_a_p_p    is a place to record a map that may be allocated.
  87.  
  88.  
  89. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  90.      When a device driver wishes to use Programmed I/O (PIO) to communicate
  91.      with a device, the system needs to have a chance to set up any
  92.      appropriate mapping registers.
  93.  
  94.      There are two different models for how to do this. The simple model
  95.      provides permanent mappings through fixed mapping resources.
  96.  
  97.      +o   _x_t_a_l_k__p_i_o_t_r_a_n_s__a_d_d_r() is generally called at device attach time to
  98.          construct a permanent address that can be used for PIO access to a
  99.          device's control registers; it attempts to use shared resources to
  100.          construct a physical address that, when used, will route transactions
  101.          to the proper target on the XIO bus.  This is not always possible,
  102.          and when it is not, the function will return NULL.
  103.  
  104.      +o   _x_t_a_l_k__p_i_o__a_d_d_r() is a wrapper function that calls
  105.          _x_t_a_l_k__p_i_o_t_r_a_n_s__a_d_d_r() to establish a mapping, and if that fails, it
  106.          then allocates a piomap using _x_t_a_l_k__p_i_o_m_a_p__a_l_l_o_c() and fills it in
  107.          using _x_t_a_l_k__p_i_o_m_a_p__a_d_d_r(), returning the resulting piomap via the map
  108.          pointer _m_a_p_p.
  109.  
  110.      It is not always possible to establish such mappings using common shared
  111.      system resources, so the concept of a PIO channel that preallocates
  112.      scarce mapping resources is provided.
  113.  
  114.      Such channels are allocated using _x_t_a_l_k__p_i_o_m_a_p__a_l_l_o_c(), which is given
  115.      the limits of the region that will be mapped, and the maximum size to be
  116.      mapped from within that region.
  117.  
  118.      +o   _x_t_a_l_k__p_i_o_m_a_p__a_d_d_r() is then used to actually establish the proper
  119.          mappings for a PIO target; given the address and the size of the
  120.          region for PIO, it will hand back the base address to be used for
  121.          accessing that region.
  122.  
  123.      +o   If the same PIO channel is to be used at different times to map
  124.          different target areas, _x_t_a_l_k__p_i_o_m_a_p__d_o_n_e() should be called to idle
  125.          any mapping hardware (and possibly flush out any pipes or buffers
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. xxxxttttaaaallllkkkk____ppppiiiioooo((((DDDD3333))))                                                    xxxxttttaaaallllkkkk____ppppiiiioooo((((DDDD3333))))
  137.  
  138.  
  139.  
  140.          along the path that might do unexpected things when mapping registers
  141.          are modified).  Then _x_t_a_l_k__p_i_o_m_a_p__a_d_d_r() can again be called,
  142.          specifying the new target area.
  143.  
  144.      When a driver is completely finished with a PIO channel -- either because
  145.      the channel is used only for initialization of the device, or because the
  146.      device or the driver is being shut down -- the PIO channel resources
  147.      should be released back to the system using _x_t_a_l_k__p_i_o_m_a_p__f_r_e_e().
  148.  
  149.  
  150. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
  151.      Here is a contrived example of how one might initialize a very strange
  152.      XIO card. It is not clear that this would be the best way to do it, but
  153.      it does give an example of the relationship between the various
  154.      functions.
  155.  
  156.      xiofoo_attach(vertex_hdl_t vhdl)
  157.      {
  158.           unsigned  *cfgspace;
  159.           struct xiofoo_devregs *devregs;
  160.           xtalk_piomap_t pmap;
  161.           xtalk_piomap_t cmap;
  162.           struct xiofoo_chan_config *tune;
  163.  
  164.           ...
  165.  
  166.           /* Get a pointer we can use for PIO to our
  167.            * device's control registers. This call
  168.            * is blindly assuming that a "piotrans"
  169.            * to the base of a widget will always work,
  170.            * which we would like to be true but may
  171.            * not be able to always guarantee.
  172.            */
  173.           devregs = xtalk_piotrans_addr(
  174.                vhdl, 0,
  175.                0, sizeof (struct xiofoo_devregs),
  176.                0);
  177.  
  178.           if (cfgspace == NULL) {
  179.                cmn_err(CE_ALERT,
  180.                     "xiofoo_attach: xtalk_piotrans_addr failed");
  181.                return -1;
  182.           }
  183.  
  184.           ...
  185.  
  186.           /* pretend our "channel" space is too big
  187.            * to successfully map with piotrans, so
  188.            * we have to use piomap, and that it is
  189.            * too big for us to get it in one call
  190.            * to piomap_addr.
  191.            *
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. xxxxttttaaaallllkkkk____ppppiiiioooo((((DDDD3333))))                                                    xxxxttttaaaallllkkkk____ppppiiiioooo((((DDDD3333))))
  203.  
  204.  
  205.  
  206.           * This would be the case, for instance,
  207.            * if the board took its 48 bits of address
  208.            * space, divided it into 16 equal pieces,
  209.            * and assigned each one to a logical portion
  210.            * of its task: on some large systems, we
  211.            * just can't keep fixed shared mapping
  212.            * resources set up for all 48 bits of all
  213.            * the widgets in the system.
  214.            */
  215.  
  216.           cmap = xtalk_piomap_alloc(vhdl, 0,
  217.                CHAN_OFFSET, CHAN_SEP * CHANS,
  218.                sizeof (struct xiofoo_chan_config), 0);
  219.  
  220.           for (chan = 0; chan < chans; ++chan) {
  221.                tune = (struct xiofoo_chan_config *)
  222.                xtalk_piomap_addr(cmap, CHAN_SEP * chan,
  223.                     sizeof (struct xiofoo_chan_config));
  224.  
  225.                /* now fiddle with this particular channel */
  226.                tune->chan = chan + 2;
  227.                tune->volume = 5;
  228.                tune->balance = 0;
  229.  
  230.                xtalk_piomap_done(cmap);
  231.           }
  232.           xtalk_piomap_free(cmap);
  233.           ...
  234.      }
  235.  
  236.  
  237. NNNNOOOOTTTTEEEESSSS
  238.      It is not necessary to separately establish mappings for each individual
  239.      PIO target register; it is more efficient to use a single mapping to
  240.      cover an entire device register set.
  241.  
  242.  
  243.  
  244. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  245.      xtalk(D3), xtalk_dma(D3), xtalk_error(D3), xtalk_get(D3), xtalk_intr(D3).
  246.  
  247.  
  248. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  249.      _x_t_a_l_k__p_i_o_t_r_a_n_s__a_d_d_r() will return a null pointer if shared (fixed)
  250.      resources can not be used to construct a valid physical address that maps
  251.      to the desired range of XIO addresses.
  252.  
  253.      _x_t_a_l_k__p_i_o_m_a_p__a_l_l_o_c() will return a null pointer if resources can not be
  254.      allocated to establish PIO mappings to the described region, or if the
  255.      parameters are inconsistent.
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. xxxxttttaaaallllkkkk____ppppiiiioooo((((DDDD3333))))                                                    xxxxttttaaaallllkkkk____ppppiiiioooo((((DDDD3333))))
  269.  
  270.  
  271.  
  272.      _x_t_a_l_k__p_i_o_m_a_p__a_d_d_r() will return a null pointer if the specified target
  273.      address can not be mapped using the specified PIO channel; this would
  274.      usually be due to specifying a target block that is outside the
  275.      previously specified target area or is larger than the previously
  276.      specified maximum mapping size.  It may also return a null pointer if the
  277.      PIO channel is currently in use and has not been marked idle by a
  278.      _x_t_a_l_k__p_i_o_m_a_p__d_o_n_e() call.
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.                                                                         PPPPaaaaggggeeee 5555
  328.  
  329.  
  330.  
  331.